Scripting
开始
文档
更新日志
隐私
开始
文档
更新日志
隐私
简体中文

写入关联数据（HealthCorrelation）

Scripting 应用允许你使用全局 API HealthCorrelation.create() 和 Health.saveCorrelation() 向 Apple HealthKit 写入相关健康数据。相关数据表示多个健康样本之间的逻辑关联，例如：

  • 一次血压测量同时包含收缩压和舒张压；
  • 一次进食记录同时包含卡路里、蛋白质、碳水等多种营养成分。

本文档将说明如何创建和保存相关样本。

什么是 Correlation（相关数据）？

Correlation 是一种将多个健康样本聚合为一个事件的机制，目前支持以下类型：

  • "bloodPressure"：包含 "bloodPressureSystolic"（收缩压）和 "bloodPressureDiastolic"（舒张压）两个样本
  • "food"：可以包含热量、蛋白质、脂肪、碳水化合物等营养成分的样本

一、创建关联的 QuantitySample

在创建相关数据前，需要先创建各个组成的 HealthQuantitySample 实例。

示例：血压测量数据

1const systolic = HealthQuantitySample.create({
2  type: "bloodPressureSystolic",
3  startDate: new Date(),
4  endDate: new Date(),
5  value: 120,
6  unit: HealthUnit.millimeterOfMercury()
7})
8
9const diastolic = HealthQuantitySample.create({
10  type: "bloodPressureDiastolic",
11  startDate: new Date(),
12  endDate: new Date(),
13  value: 80,
14  unit: HealthUnit.millimeterOfMercury()
15})

请确保创建成功（返回值不为 null）后再继续。

二、创建 Correlation 实例

使用 HealthCorrelation.create() 创建相关数据对象。

参数说明

参数 类型 描述
type "bloodPressure" 或 "food" 相关类型
startDate Date 事件开始时间
endDate Date 事件结束时间
objects (HealthQuantitySample | HealthCategorySample)\[] 包含的健康样本数组
metadata Record<string, any>（可选） 附加元数据（如来源说明）

示例

1const correlation = HealthCorrelation.create({
2  type: "bloodPressure",
3  startDate: systolic.startDate,
4  endDate: systolic.endDate,
5  objects: [systolic, diastolic],
6  metadata: {
7    source: "ScriptingApp"
8  }
9})
10
11if (!correlation) {
12  throw new Error("创建 Correlation 失败")
13}

三、保存到 HealthKit

使用 Health.saveCorrelation() 将创建的相关数据写入 HealthKit：

1await Health.saveCorrelation(correlation)

完整示例：写入一次血压记录

1async function writeBloodPressure() {
2  const systolic = HealthQuantitySample.create({
3    type: "bloodPressureSystolic",
4    startDate: new Date(),
5    endDate: new Date(),
6    value: 120,
7    unit: HealthUnit.millimeterOfMercury()
8  })
9
10  const diastolic = HealthQuantitySample.create({
11    type: "bloodPressureDiastolic",
12    startDate: new Date(),
13    endDate: new Date(),
14    value: 80,
15    unit: HealthUnit.millimeterOfMercury()
16  })
17
18  if (!systolic || !diastolic) {
19    console.error("样本创建失败")
20    return
21  }
22
23  const correlation = HealthCorrelation.create({
24    type: "bloodPressure",
25    startDate: systolic.startDate,
26    endDate: systolic.endDate,
27    objects: [systolic, diastolic],
28    metadata: {
29      note: "手动记录"
30    }
31  })
32
33  if (!correlation) {
34    console.error("Correlation 创建失败")
35    return
36  }
37
38  try {
39    await Health.saveCorrelation(correlation)
40    console.log("血压数据写入成功")
41  } catch (err) {
42    console.error("保存失败：", err)
43  }
44}
45
46writeBloodPressure()

注意事项

  • 所有样本的时间范围（startDate / endDate）应一致或合理重叠；

  • "bloodPressure" 类型必须包含 收缩压 和 舒张压 两个样本；

  • "food" 类型可包含多个营养成分样本，如：

    • "dietaryEnergyConsumed" → HealthUnit.kilocalorie()
    • "dietaryProtein" → HealthUnit.gram()
    • "dietaryCarbohydrates" → HealthUnit.gram()

  • 如果传入的参数不合法或缺少必要样本，HealthCorrelation.create() 将返回 null。

大纲